<html>
<head>
<title>Project 1 </title>
</head>
<body bgcolor="#ffffff">
<h1 align="center">Project 1 </h1>
<p>
<b>Due Date</b>:  Feb 15, by midnight.
</p>
<p>
[<b>Important Note</b>: If you are reading the <a href="./prj1.umt">./prj1.umt</a> version of this
document, please be aware of the fact that it is really the source code for
the <tt>HTML</tt> <a href="./prj1.html">./prj1.html</a> and <tt>PDF</tt> <a href="./prj1.pdf">./prj1.pdf</a> versions.  Hence it
contains markup; usually the markup is quite unobstrusive, but sometimes it
gets in the way.  In particular, some <tt>*</tt>'s and quotes may not make sense as
they are also used for markup.]
</p>
<p>
The document first describes the aims of this project.  It then gives the
requirements as explicitly as possible.  It describes the files which are
being provided and hints at how the project may be implemented.  Finally, it
lists exactly what needs to be submitted.
</p>
<h2>Aims</h2>
<p>
The aims of this project are as follows:
</p>
<ul>
<p><li>
To introduce you to programming in C.
</p>
<p><li>
To familiarize you with the tools typically used for program development
    in a Unix environment.
</p>
</ul>
<h2>Requirements</h2>
<p>
Write a program which integrates functions using the trapezoidal rule.
Specifically, write a program with executable <tt>prj1</tt> which takes a single
fixed argument <tt>trapezoidal</tt>.  If called with the incorrect number of
arguments, the program should print a short summary of its usage, including
the expected format of its input.
</p>
<p>
When run, the program should read lines from <tt>stdin</tt>, where each line
contains 4 whitespace separated tokens:
</p>
<pre>
    FN LO_BOUND HI_BOUND N_INTERVALS
</pre>
<p>
where:
</p>
<dl>
<p><dt><tt>FN</tt><dd>
    is the name of a function known by the program referring to the
    function which is to be integrated.
</p>
<p><dt><tt>LO_BOUND</tt><dd>
    is the textual representation of a <tt>double</tt> representing the
    lower bound of a integral.
</p>
<p><dt><tt>HI_BOUND</tt><dd>
    is the textual representation of a <tt>double</tt> representing the
    upper bound of a integral.
</p>
<p><dt><tt>N_INTERVALS</tt><dd>
    is the textual representation of a <tt>int</tt> representing the
    number of intervals over which the integral should be evaluated.
</p>
</dl>
<p>
The program should then print on standard output a line containing the
result of evaluating the integral of <tt>FN</tt> from <tt>LO_BOUND</tt> to <tt>HI_BOUND</tt>
using the <a href="http://en.wikipedia.org/wiki/Trapezoidal_rule">trapezoidal-rule</a>
using <tt>N_INTERVALS</tt> steps.  The result should be printed using the <tt>printf</tt>
format <tt>%.6g</tt>.
</p>
<p>
The functions being integrated should be provided to the program using a
object module <tt>fns.o</tt> compiled from a C module <tt>fns.c</tt> which provides
definitions for the two variables <tt>fns</tt> and <tt>nFns</tt> defined in the header
file <a href="./files/fns.h">./files/fns.h</a>.  Specifically, <tt>fns.c</tt> should define an array <tt>fns[]</tt>
with each element containing the name by which a function is referred to in
the program and a pointer to the code of the function; it should also define
a <tt>int</tt> variable <tt>nFns</tt> containing the number of entries in the <tt>fns[]</tt>
array.
</p>
<p>
The implementation is subject to the following additional restrictions:
</p>
<ul>
<p><li>
The program should check for input errors and if it encounters an error
    it should output a meaningful error message to <tt>stderr</tt> and then
    continue evaluating the next line.
</p>
<p><li>
The program should check for all resource errors and terminate after
    outputting a meaningful error message to <tt>stderr</tt>.
</p>
<p><li>
All I/O should be performed using only the standard C library.
</p>
<p><li>
It should be possible to compile the source program to produce
    a working executable on any system having a C compiler and run-time
    environment without needing to make any changes to the source program.
</p>
<p><li>
There should not be any implementation limits beyond those caused by
    resource limitations.  For example, there should not be any fixed
    limit on the length of the name of the function being integrated.
</p>
</ul>
<h2>Provided Files</h2>
<p>
Some routines which may prove useful have been packaged into a <tt>lib551s10</tt>
library which can also be used in future projects.
</p>
<dl>
<p><dt><a href="../../src/libcs551/">Source</a><dd>
    The library source directory which contains all the <tt>.c</tt> files for the
    library, including a <tt>Makefile</tt> which compiles the library and contains
    a <tt>install</tt> target which installs the library in <a href="../../lib">../../lib</a>.
</p>
<p><dt><a href="../../include/">Include</a><dd>
    The library include directory which contains all the <tt>.h</tt> files for the
    library.  You will need to <tt>#include</tt> these header files in your
    project files.  This is usually done using <tt>gcc</tt>'s <tt>-I</tt> option to add
    this directory to the include-path.
</p>
<p>
    The library provides the following modules:
</p>
<dl>
<p><dt><a href="../../include/errors.h">errors</a><dd>
      A module for printing out and tracking errors.
</p>
<p><dt><a href="../../include/getline.h">getline</a><dd>
      A module for reading a line into a dynamically grown buffer.
</p>
<p><dt><a href="../../include/memalloc.h">memalloc</a><dd>
      A module which provides wrappers around the standard memory-allocation
      routines which check for a <tt>NULL</tt> return value and terminate the
      program if such a <tt>NULL</tt> is found.
</p>
</dl>
</dl>
<p>
To use the library, the library must be included into the compilation using
the switches <tt>-L $HOME/cs551s10/lib -lcs551fs10</tt>.  At run-time it must be
made available by setting the environmental variable <tt>LD_LIBRARY_PATH</tt>
to contain <tt>$HOME/cs551s10/lib</tt> (this should have been taken care of if you
have setup your account as requested in the <a href="../../misc/startup/startup.html">startup-directions</a>.
</p>
<p>
The <a href="./files/">./files/</a> directory contains the following files:
</p>
<dl>
<p><dt><a href="./files/Makefile">Makefile</a><dd>
    This file can be used to build your overall project by simply invoking
    the command <tt>make</tt> in the directory containing it and all source files.
    It assumes that your code is setup in the following files:
</p>
<ul>
<p><li>
<tt>fns.h</tt> with implementation file <tt>fns.c</tt> defining the functions
        available for integration.
</p>
<p><li>
<tt>trapezoidal.h</tt> with implementation file <tt>trapezoidal.c</tt> defining
        the code which implements the integration of a function (specified
        by a function pointer) from some lower bound to some upper bound
        (specified by <tt>double</tt>'s) using the trapezoidal rule over some
        number of intervals (specified by an <tt>int</tt>).
</p>
<p><li>
<tt>main.c</tt> which contains the main program and code which repeatedly
        reads and parses input lines, calls the function (in
        <tt>trapezoidal.c</tt>) to evaluate integrals and prints out the result.
</p>
</ul>
<p>
    This provided <tt>Makefile</tt> takes care of linking in the <tt>cs551f10</tt> library
    at compile-time.
</p>
<p><dt><a href="./files/fns.h">./files/fns.h</a><dd>
    The header file which specifies how the functions to be integrated
    are made available to the program.
</p>
<p><dt><a href="./files/fns.c">./files/fns.c</a><dd>
    A sample file containing a couple of functions which can be integrated.
</p>
</dl>
<h2>Hints</h2>
<p>
There are two aspects to this project:
</p>
<ol type="A">
<p><li>
Writing a function which evaluates an integral using the trapezoidal
     rule.
</p>
<p><li>
Reading and parsing the input and reporting input errors without
     putting any limits on the parameters (beyond those posed by the
     operating environment).
</p>
</ol>
<p>
Both aspects are easy, but (B) is somewhat more involved than (A).
</p>
<p>
You may proceed as follows (the following steps are not prescriptive):
</p>
<ol type="1">
<p><li>
Write a prototype for the function which will do the integration
      in header file <tt>trapezoidal.h</tt> taking care to protect that file
      against multiple inclusion.
</p>
<p><li>
Write a implementation of your integration function in file
      <tt>trapezoidal.c</tt> ensuring consistency with your prototype in
      <tt>trapezoidal.h</tt> by <tt>#include</tt>'ing it.
</p>
<p><li>
Add a <tt>main()</tt> function in <tt>trapezoidal.c</tt> which will be compiled in
      only if a preprocessor symbol like <tt>TRAPEZOIDAL_TEST</tt> is defined (use
      a <tt>#ifdef</tt>).  The main function should invoke the integration function
      with fixed arguments to integrate one or more of the provided
      functions and print out the result.  Setup the compilation to ensure
      that the <tt>TRAPEZOIDAL_TEST</tt> preprocessor symbol is defined (using the
      <tt>-D</tt> compiler switch) and that the <tt>fns</tt> module is linked in.  The
      provided <a href="./files/Makefile">Makefile</a> provides a <tt>trapezoidal-test</tt>
      target which should build the test using the command <tt>make
      trapezoidal-test</tt>.  Run the resulting executable to ensure that your
      integration function is working ok.
</p>
<p><li>
In a separate file <tt>main.c</tt> write a main program which invokes
      functions which read and parse lines from the input and invoke the
      integration function.  Routines from the <tt>cs551f10</tt> library may prove
      useful as could routines from the standard C library like <tt>scanf()</tt>,
      <tt>sscanf()</tt>, <tt>strtok()</tt>, <tt>strchr()</tt>, <tt>strtod()</tt>, <tt>strtol()</tt>, etc.  You
      can obtain documentation on a function <i>F</i> by using the command <tt>man</tt>
      <i>F</i> at the Unix prompt.
</p>
<p><li>
Refactor the program to clean it up.  Make sure that all
      resources are returned to the system before successful termination of
      the program.
</p>
<p><li>
Iterate the previous steps until your program meets all the
      specifications.
</p>
</ol>
<h2>Submission</h2>
<p>
You should submit a archive <tt>prj1.tar.gz</tt> which contains all the source
files needed to build your project.
</p>
<ul>
<p><li>
The archive should not contain any executable or object files.
</p>
<p><li>
The provided <a href="./files/Makefile">Makefile</a> contains a <tt>submit</tt>
    target such that typing <tt>make submit</tt> will build the required
    <tt>prj1.tar.gz</tt> archive.  This presupposes that you have edited the
    <tt>Makefile</tt> to adjust it if you have a different organization for your
    source files than that outlined above.
</p>
<p><li>
The archive <b>must</b> contain a <tt>Makefile</tt> such that typing <tt>make</tt> in the
    directory containing the unpacked archive should build your project's
    main executable <tt>prj1</tt>.  You can test this before submission, by
    unpacking your archive into an empty directory and checking to see
    whether typing <tt>make</tt> builds correctly.
</p>
<p><li>
Your submission <b>must</b> include a <tt>README</tt> file which minimally contains
    at least your name and ID number.  It can optionally contain any
    comments you feel are relevant to the project like what works, what does
    not work, what you feel is neat, logs of test cases, etc.
</p>
<p><li>
Your submission should include any files from the <a href="./files">./files</a> directory
    your project uses, whether you modified them or not.  You will not need
    to modify the <tt>Makefile</tt> if you use exactly the same names and
    organization as that in the provided <a href="./files/Makefile">Makefile</a>.
</p>
<p><li>
You do not need to include any files used from the <tt>cs551s10</tt> library.
</p>
</ul>
<p>
The above archive should be email'd as an attachment to the TA at
<a href="mailto:ruiqi.luo@gmail.com">mailto:ruiqi.luo@gmail.com</a> with subject set to <tt>CS 451/551 Project 1</tt>.  If
you discover a mistake in your submitted project before the due date, you
may submit it again; only the latest submission will be graded.
</p>
</body>
</html>
